home *** CD-ROM | disk | FTP | other *** search
/ Beginning Mac Programming / Beginning Mac Programming.bin / Open Me for REALbasic 3 / REALbasic 3.2 / Example Projects / Techniques / Examples by Thomas Tempelmann / TT's CatSearch-Plugin / CatSearch Plugin - ReadMe next >
Text File  |  1999-07-01  |  7KB  |  130 lines
  1. TT's CatSearch-Plugin for REALbasic
  2.  
  3. General Information
  4.  
  5. By Thomas Tempelmann
  6. Current version: 1.2 (March 8, 1999)
  7.  
  8. This is freeware. Use it as you like.
  9. (And if you have created some nice things, think about sharing them, too!)
  10.  
  11. This is a Plugin for REALbasic. Plugins contain usually low-level code that cannot be written using the REALbasic language directly.
  12.  
  13. The plugin and the sample RB program were created using CodeWarrior Pro 3 and REALbasic 1.1.1, tested on PowerPC computers running OS 8.5 and 7.6.1.
  14.  
  15. More REALbasic examples can be found on my Web Site at
  16.  
  17.   <http://www.tempel.org/rb>
  18.  
  19. Enjoy!
  20.  
  21.  
  22. Overview
  23.  
  24. This plugin implements the PBCatSearch function of the Mac OS File Manager. This is a very fast routine to find specific types of files on a volume. The MacOS tool Sherlock (aka Find File) uses this function to its quick search on local volumes.
  25.  
  26. There's some restrictions to CatSearch: Is it not supported on every volume! Whether it is supported or not depents on the File System format used on the Volume: HFS, HFS+ and most File Servers support it, while Floppy Disks, ISO 9660 and UDF formatted disks might not support it.
  27.  
  28. That means that if you want to take advantage of this function, you need to be able to handle the cases of volumes not supporting CatSearch in some way: Either do not support searching on them at all or use the classic technique: Recursively step through all directories on the volume, starting at the root dir level, and do compare each of the items against your search criteria. An example in C-language for accomplishing this is given in the "MoreFiles" sample code, available from Apple's developer web site.
  29.  
  30.  
  31. Installation
  32.  
  33. 1. Quit REALbasic if it is running
  34.  
  35. 2. Place the file TT's CatSearch-Plugin into a folder called Plugins, that resides in the same folder where your REALbasic application is.
  36.  
  37. 3. Now you can launch REALbasic again and the methods described below will be available for your RB applications and the enclosed demo code.
  38.  
  39.  
  40. Plugin Functions
  41.  
  42. • VolSupportsCatSearch(volume as FolderItem) as Boolean
  43.  
  44. Returns true if the volume is valid and supports the CatSearch functions. Returns false otherwise.
  45.  
  46. • CatSearchOpen(volume as FolderItem) as Integer
  47.  
  48. Call this to initiate a search. If the returned value is 0, then an error has occured (either there's not enough free memory or the volume wasn't valid). If the returned value is not zero, save it - it is your handle to be used for all the other calls.
  49.  
  50. • CatSearchClose(handle as Integer)
  51.  
  52. Finishes the search. You should make sure that you always call this function when you're done, because CatSearchOpen did allocate some memory and will be freed only by calling CatSearchClose.
  53.  
  54. • CatSearchSetFileType(handle as Integer, fileType as String) as Boolean
  55. • CatSearchSetCreator(handle as Integer, creator as String) as Boolean
  56. • CatSearchSetFileFlags(handle as Integer, mask as Integer, selector as Integer) as Boolean
  57.  
  58. The above Set... functions allow you to specifiy the search criteria. Without calling any of them, a search will find nothing. Calling any of the Set... functions includes a certain kind to be be searched for.
  59. However, you cannot call any of the Set... functions multiple times, like calling CatSearchSetCreator twice with two different creator codes to search for - only value of each kind can be searched for.
  60.  
  61. CatSearchSetFileFlags takes a mask and a selector: bits set in the mask specifiy which bits in the selector shall be checked for equality with the items on the volume.
  62. The meaning of the flags are as follows (you can use BitwiseOr to assemble them):
  63.     • bit 15, value &H8000: isAlias
  64.     • bit 14, value &H4000: isInvisible
  65.     • bit 13, value &H2000: hasBundle (has a BNDL resource)
  66.     • bit 12, value &H1000: nameLocked
  67.     • bit 11, value &H0800: isStationary
  68.     • bit 10, value &H0400: hasCustomIcon
  69.     • bit 8, value &H0100: hasBeenInited (Finder has seen the file since it has been created)
  70.     • bit 7, value &H0080: hasNoINITs (there's no INIT rsrc in the Extension file)
  71.     • bit 6, value &H0040: isShared
  72.     • bits 1-3, value &H000E: color (as a 3-bit value from 0-7)
  73.  
  74. For more information see Inside Macintosh, File Manager.
  75.  
  76. • CatSearchNext(handle as Integer) as Integer
  77.  
  78. Once the search criteria has been set, call this function repeatedly as long as it returns 0, which means that a match has been found, and the found item can be inquired by calling CatSearchGetItem.
  79. Once the result is non-zero, the search is finished and CatSearchClose should be called.
  80. Typical returned non-zero values are:
  81.     -50 (paramErr): This volume does not support CatSearch
  82.     -39 (eofErr): end of search, no more matches
  83.     -1304 (catalogChangedErr): files or folders were added or removed to the volume (suggesting that you restart the search).
  84.  
  85. • CatSearchGetItem(handle as Integer) as FolderItem
  86.  
  87. After CatSearchNext has returned zero, this functions returns the found file or folder.
  88.  
  89. See the RB project CatSearch-Demo.π for an example how to use these functions: The demo searches the boot volume for files of type "INIT" and for invisible files (The same can be done in Sherlock (or Find File) - it should present the same results).
  90.  
  91.  
  92. Plugin Programming Information
  93.  
  94. This plugin also shows how you can allow your RB app to access complex data structures inside the plugin without having to create a REALbasic Control (the trick is that you create a temporary structure inside the plugin and then provide accessor functions to get and set the individual elements of that structure. See the CatSearch code for an example).
  95.  
  96. The plugin code is a Metrowerks CodeWarrior Pro 3 (IDE 3.1) project.
  97. If you have an older CW version that refuses to open the prj file, then create a new and set/enable the following prj options:
  98. • create 68K target (set to 68K linker)
  99. • prj type: Code Resource, File Name "CatalogSearch-Plugin", Creator "SfTg", Type "RBPl", ResType "PL68", ResID "128", Extended Resource, Header Type "Standard"
  100. • C/C++ language settings: Prefix File "MacHeaders.h"
  101. • 68K Processor: 68020 Codegen, Code Model "Smart", Struct Alignm. "PowerPC", 4-Byte Ints, 8-Byte Doubles, MPW C Call. Conv.
  102. • 68K Linker: Link Single Segment, Merge Compiler Glue…, Dead-strip Static Init Code
  103. • Add the files "Plugin Source.cpp", "PluginMain.cpp", "MacOS.lib", "Version Info.rsrc" and a 68K C lib with (4i_8d) in its name to the project.
  104.  
  105. To compile the project, you also need to have the "Plugin SDK" available, which you can download from RB's website.
  106.  
  107.  
  108. Revision history
  109.  
  110. 9 Feb 99:
  111.     First release.
  112.  
  113. 12 Feb 99:
  114.     Bug fixed in IsRemoteVol that could cause crashes (bus errors).
  115.  
  116. 13 Feb 99:
  117.     CatSearchSetFileFlags() added;
  118.     VolSupportsCatSearch() added.
  119.  
  120. 27 Feb 99:
  121.     Added an exception handler to the "DoTheSearch" method and a
  122.     flag to show when no files were found.
  123.  
  124. 8 Mar 99, v1.2
  125.     - Moved the non-CatSearch related functions to a new plugin module (called TT's FileMgr-Plugin).
  126.     - Renamed this plugin to TT's CatSearch-Plugin.
  127.     - Added some more Set-functions.
  128.     - Added more example code to the RB demo prj file.
  129.     - Improved the documentation in this ReadMe.
  130.